3 * This program is free software; you can redistribute it and/or modify
4 * it under the terms of the GNU General Public License as published by
5 * the Free Software Foundation; either version 2 of the License, or
6 * (at your option) any later version.
8 * This program is distributed in the hope that it will be useful,
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 * GNU General Public License for more details.
13 * You should have received a copy of the GNU General Public License along
14 * with this program; if not, write to the Free Software Foundation, Inc.,
15 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
16 * http://www.gnu.org/copyleft/gpl.html
21 namespace Wikimedia\Rdbms
;
23 use InvalidArgumentException
;
26 * Class to handle database/schema/prefix specifications for IDatabase
28 * The components of a database domain are defined as follows:
29 * - database: name of a server-side collection of schemas that is client-selectable
30 * - schema: name of a server-side collection of tables within the given database
31 * - prefix: table name prefix of an application-defined table collection
33 * If an RDBMS does not support server-side collections of table collections (schemas) then
34 * the schema component should be null and the "database" component treated as a collection
35 * of exactly one table collection (the implied schema for that "database").
37 * The above criteria should determine how components should map to RDBMS specific keywords
38 * rather than "database"/"schema" always mapping to "DATABASE"/"SCHEMA" as used by the RDBMS.
40 class DatabaseDomain
{
41 /** @var string|null */
43 /** @var string|null */
48 /** @var string Cache of convertToString() */
49 private $equivalentString;
52 * @param string|null $database Database name
53 * @param string|null $schema Schema name
54 * @param string $prefix Table prefix
56 public function __construct( $database, $schema, $prefix ) {
57 if ( $database !== null && ( !is_string( $database ) ||
$database === '' ) ) {
58 throw new InvalidArgumentException( 'Database must be null or a non-empty string.' );
60 $this->database
= $database;
61 if ( $schema !== null && ( !is_string( $schema ) ||
$schema === '' ) ) {
62 throw new InvalidArgumentException( 'Schema must be null or a non-empty string.' );
63 } elseif ( $database === null && $schema !== null ) {
64 throw new InvalidArgumentException( 'Schema must be null if database is null.' );
66 $this->schema
= $schema;
67 if ( !is_string( $prefix ) ) {
68 throw new InvalidArgumentException( "Prefix must be a string." );
70 $this->prefix
= $prefix;
74 * @param DatabaseDomain|string $domain Result of DatabaseDomain::toString()
75 * @return DatabaseDomain
77 public static function newFromId( $domain ) {
78 if ( $domain instanceof self
) {
82 $parts = array_map( [ __CLASS__
, 'decode' ], explode( '-', $domain ) );
87 if ( count( $parts ) == 1 ) {
88 $database = $parts[0];
89 } elseif ( count( $parts ) == 2 ) {
90 list( $database, $prefix ) = $parts;
91 } elseif ( count( $parts ) == 3 ) {
92 list( $database, $schema, $prefix ) = $parts;
94 throw new InvalidArgumentException( "Domain '$domain' has too few or too many parts." );
97 if ( $database === '' ) {
101 if ( $schema === '' ) {
105 $instance = new self( $database, $schema, $prefix );
106 $instance->equivalentString
= (string)$domain;
112 * @return DatabaseDomain
114 public static function newUnspecified() {
115 return new self( null, null, '' );
119 * @param DatabaseDomain|string $other
120 * @return bool Whether the domain instances are the same by value
122 public function equals( $other ) {
123 if ( $other instanceof self
) {
125 $this->database
=== $other->database
&&
126 $this->schema
=== $other->schema
&&
127 $this->prefix
=== $other->prefix
131 return ( $this->getId() === $other );
135 * Check whether the domain $other meets the specifications of this domain
137 * If this instance has a null database specifier, then $other can have any database
138 * specifier, including null. This is likewise true if the schema specifier is null.
139 * This is not transitive like equals() since a domain that explicitly wants a certain
140 * database or schema cannot be satisfied by one of another (nor null). If the prefix
141 * is empty and the DB and schema are both null, then the entire domain is considered
142 * unspecified, and any prefix of $other is considered compatible.
144 * @param DatabaseDomain|string $other
148 public function isCompatible( $other ) {
149 if ( $this->isUnspecified() ) {
150 return true; // even the prefix doesn't matter
153 $other = self
::newFromId( $other );
156 ( $this->database
=== $other->database ||
$this->database
=== null ) &&
157 ( $this->schema
=== $other->schema ||
$this->schema
=== null ) &&
158 $this->prefix
=== $other->prefix
166 public function isUnspecified() {
168 $this->database
=== null && $this->schema
=== null && $this->prefix
=== ''
173 * @return string|null Database name
175 public function getDatabase() {
176 return $this->database
;
180 * @return string|null Database schema
182 public function getSchema() {
183 return $this->schema
;
187 * @return string Table prefix
189 public function getTablePrefix() {
190 return $this->prefix
;
196 public function getId() {
197 if ( $this->equivalentString
=== null ) {
198 $this->equivalentString
= $this->convertToString();
201 return $this->equivalentString
;
207 private function convertToString() {
208 $parts = [ (string)$this->database
];
209 if ( $this->schema
!== null ) {
210 $parts[] = $this->schema
;
212 if ( $this->prefix
!= '' ||
$this->schema
!== null ) {
213 // If there is a schema, then we need the prefix to disambiguate.
214 // For engines like Postgres that use schemas, this awkwardness is hopefully
215 // avoided since it is easy to have one DB per server (to avoid having many users)
216 // and use schema/prefix to have wiki farms. For example, a domain schemes could be
217 // wiki-<project>-<language>, e.g. "wiki-fitness-es"/"wiki-sports-fr"/"wiki-news-en".
218 $parts[] = $this->prefix
;
221 return implode( '-', array_map( [ __CLASS__
, 'encode' ], $parts ) );
224 private static function encode( $decoded ) {
227 $length = strlen( $decoded );
228 for ( $i = 0; $i < $length; ++
$i ) {
229 $char = $decoded[$i];
230 if ( $char === '-' ) {
232 } elseif ( $char === '?' ) {
242 private static function decode( $encoded ) {
245 $length = strlen( $encoded );
246 for ( $i = 0; $i < $length; ++
$i ) {
247 $char = $encoded[$i];
248 if ( $char === '?' ) {
249 $nextChar = $encoded[$i +
1] ??
null;
250 if ( $nextChar === 'h' ) {
253 } elseif ( $nextChar === '?' ) {
270 function __toString() {
271 return $this->getId();